1. Plan

2. Avant-propos

Dilbert
Figure 1. Produire des applications

Nous allons nous intéresser dans ce cours aux Méthodologies de la Production d'Application.

Ce module, qui fait suite aux modules de programmation (M2103), conception (M2104) et d’IHM (M2105), est fortement corrélé au module de conception avancé (M3105).

Note

Nous suivons (comme tous les DUT informatique) le programme pédagogique national (PPN - disponible ici).

M3301
Figure 2. Le contenu officiel

2.1. À qui est destiné ce document?

Les étudiants du DUT informatique, mes collègues enseignants qui cherchent un document de référence accessible, et …​ moi-même (pour organiser mes notes diverses)!

2.2. À qui il n’est pas destiné?

Si vous appartenez à une de ces catégories, ce document n’est pas pour vous :

  • vous cherchez un document de référence

  • vous voulez vous perfectionner

  • vous souhaitez préparer une certification Java ou UML™.

2.3. Historique

Ce document est tout nouveau (date de naissance 05/09/2014!), donc merci de votre indulgence …​

Vous trouverez en référence (cf. Bibiliographie) les ouvrages et autres documents utilisés.

2.4. Sur l’auteur

  • Professeur à l’Université de Toulouse, en poste à l’IUT de Blagnac

  • Co-fondateur de l’association SysML-France

  • Membre du comité éditorial de la revue SoSyM

  • Membre du Steering Committee de la conférence ACM/IEEE MODELS

  • Chef du département informatique de l’IUT de Blagnac 2009 à 2012

  • Responsable de l’ancien module (Analyse et Conception des Systèmes d’Information)

  • Marié à une merveilleuse femme, papa d’une merveilleuse fille

2.5. Comment lire ce document?

Ce document a été réalisé de manière à être lu de préférence dans sa version électronique (au format HTML ou PDF), ce qui permet de naviguer entre les références et les renvois interactivement, de consulter directement les documents référencés par une URL, etc.

Warning Si vous lisez la version papier de ce document, ces liens clickables ne vous servent à rien, et c’est votre punition pour avoir utilisé du papier au lieu du support électronique!

2.5.1. Conventions typographiques

J’ai utilisé un certain nombre de conventions personnelles pour rendre ce document le plus agréable à lire et le plus utile possible, grâce notamment à la puissance d’AsciiDoc :

  • Les références bibliographiques présentées en fin de document (cf. Bibliographie).

  • Les termes anglais (souvent incontournables) sont repérés en italique, non pas pour indiquer qu’il s’agit d’un mot anglais, mais pour indiquer au lecteur que nous employons volontairement ces termes (e.g., Package).

Le titre des figures indique (entre parenthèses) un M pour les figures issues de Modelio, un MD pour les figures issues de MagicDraw, un P pour les figures issues de plantUML, un Py pour les figures issues de Papyrus, un R pour les figures issues de Rhapsody, un T pour les figures issues de TOPCASED, un Y pour les figures issues de yuml, et un UK pour les figures en anglais.

Pour les notes, conseils, avertissements, etc. voici la liste des pictogrammes utilisés :

Note

Les notes comme celles-ci sont utilisées pour indiquer des éléments intéressant pour la majorité des lecteurs.

Caution

Ces notes indiquent des points importants qui réclament votre attention.

Tip

Celles-ci concernent en général des points de détail et permettent "d’aller plus loin".

Note
Définition : Exemple (OMG UML v2.4.1, p. 152)

Ces notes concernent des définitions tirées de la spécification UML™ et sont donc précisément référencées.

Note

Modélisation UML incorrecte.

Note

Modélisation UML partiellement correcte ou pouvant prêter à confusion.

Note

Modélisation UML correcte.

2.6. Pourquoi parler de "document"?

Parce que j’ignore la version que vous êtes en train de lire. À partir de l’original, plusieurs versions ont été générées grâce à AsciiDoc :

  • Une version pour le web (Moodle) au format html

  • Une version pour présentation en amphi au format présentation

  • Une version pour impression au format pdf

2.7. Utilisation et autres mentions légales

Les images qui ne sont pas libres de droit contiennent un lien vers les sites où je les ai "empruntées".

N’hésitez pas à m’envoyer vos remarques en tout genre en m’écrivant ici.

2.8. Organisation et généralités

Ce support de cours est destiné en priorité aux étudiants de l’IUT de Blagnac.

Comme déjà indiqué, ce module est fortement corrélé au module de Conception et Programmation Objet Avancées (CPOA - M3105).

Il ne concerne que la partie modélisation du cours, les autres aspects étant couverts par Jean-Michel Inglebert. Il est prévu pour 2 cours d'1h30, complété par des mises en oeuvre en TD et en TP. Cette partie du cours va principalement porter sur UML™, le langage universel de modélisation très utilisé en entreprise que vous maîtrisez déjà en partie.

3. Introduction

La matrice qui nous servira de "carte de base" pour placer les activités ou les modèles, sera celle-ci :

Table 1. La carte de base
Requirements Structure Comportement Transverse

Organisation

Analyse

Conception

Implémentation

Cette matrice permet de situer les différents éléments qui seront vus dans ce cours dans un cadre utile pour comparer ces éléments les uns aux autres. Je vous conseille de vous faire votre propre matrice. L’essentiel est de toujours bien se représenter les différents éléments qu’on aborde dans une carte mentale précise. Cela permet une meilleure mémorisation.

3.1. Points de vue

Dans un axe horizontal, j’ai différencié quatre grands points de vue :

Requirements

Les exigences et leur prises en compte sont un éléments critique pour le succès du développement de tout système. Sans explorer l’ensemble des activités d’ingénierie système (ce qui nécessiterait tout un volume du type de Les exigences) nous insisterons ce semestre sur cet aspect.

Structure

La description de l’architecture et des éléments constitutifs du système, avec les blocs, leurs relations, organisations internes, etc. constituera un point de vue important. C’est souvent la partie de modélisation qui pose le moins de problème aux débutants.

Comportement

Le comportement d’un système est du point de vue de l’utilisateur final beaucoup plus important que la structure elle-même. C’est la partie qu’il est la plus à même d’exprimer, de comprendre (vos modèles) et de valider.

Transverse

Un certains nombre de concepts sont transverses aux trois points de vue précédents. Il s’agira principalement de parler de cohérence ou de traçabilité entre les phases de développement ou entre les points de vue.

Ces différents points de vue ne doivent pas être confondus avec les différentes phases de développement (cf. paragraphe suivant). Ils sont plutôt à rapprocher de la notion de préoccupation. C’est ainsi que j’ai choisi de distinguer trois points de vue qui se retrouvent souvent en modélisation : le point de vue des exigences qui permet de se focaliser sur les besoins des clients ; le point de vue structurel qui permet de se focaliser sur les différents composants du système ; et le point de vue comportemental qui permet de se focaliser sur le comportement du système. Ces trois points de vue n’étant pas indépendants les uns des autres, j’ai intégré un quatrième point de vue transversal.

3.2. Phase de développement

Dans un axe vertical, j’ai différencié quatre grandes phases du cycle de vie du développement :

Organisation

Une étape indépendante du type de cycle de développement envisagé (en V, agile, etc.) mais qui concerne la mise en place d’un cadre de travail qui permette un développement de qualité (outils, éditeurs, gestionnaire de version, de tâches, etc.).

Note

On pourrait rapprocher cette étape du "cycle 0" de Scrum.

Analyse

Cette phase vise plutôt à examiner le domaine du problème. Elle se focalise sur les cahiers des charges et les exigences. L’analyse débouche sur un dossier d’analyse qui décrit les grandes lignes (cas d’utilisation, architecture principale) du système.

Conception

Cette phase vise plutôt à examiner le domaine de la solution. Elle débouche sur un dossier de conception qui décrit les détails conceptuels de la solution envisagée (structure détaillée, comportement, etc.)

Implémentation

Cette phase traite des développements finaux (construction ou approvisionnement en matériel, développement de codes, etc.).

Il s’agit ici classiquement des grandes étapes de développement d’un système. On pourrait être surpris par l’étape que j’ai appelé « organisation ». C’est une étape que je considère importante, particulièrement pour l’enseignement. Avant toute activité de modélisation ou de même de développement, il convient en effet de s’organiser en termes de choix d’outils, choix d’environnement, etc. Cette étape est souvent négligée par les étudiants. C’est pour cela que j’ai décidé de faire figurer cette étape de manière explicite. Bien sûr dans une organisation existante cette étape sera contrainte par les habitudes « maison ».

3.3. Questions de révision

Note
  1. Associez les diagrammes suivants avec leurs acronymes :

    Diagramme de Paquetages

    sd

    Diagramme des Cas d’Utilisation

    dc

    Diagramme de Séquences Système

    uc

    Diagramme de Classes

    pkg

    Diagramme de Séquences

    dss

  2. Placez dans la matrice ci-dessous les différents diagrammes UML™ que vous connaissez déjà (sd, dc, uc, pkg, dss.

    Requirements Structure Comportement Transverse

    Organisation

    Analyse

    Conception

    Implémentation

4. Les exigences

L’ingénierie des exigences est d’une importance capitale, surtout en Ingénierie Système. En général les exigences sont exprimées par des ingénieurs dédiés à cette activité. La complexité des systèmes modernes (embarqués, communicants, critiques, …​) rendent cruciale cette analyse.

Joke
Figure 3. 300 corps de métiers sont parfois présents sur un même chantier
Tip
Besoins, exigences : question de vocabulaire

La difficulté de l’emploi massif de l’anglais fait qu’il existe souvent une confusion entre les termes anglais et leurs traduction française. Nous précisons donc ici notre utilisation des termes :

Requirements

Exigences, c’est à dire une fonction ou une propriété que doit satisfaire le système considéré. Par nature une exigence doit pouvoir être vérifiable. En génie logiciel on parle plus classiquement des spécifications ("spec") pour parler des contraintes à respecter pour un système. Les ingénieurs systèmes ont depuis longtemps intégré le terme d’exigences comme traduction directe de requirement.

Besoins

Il s’agit des exigences du client. En UML™ on va plus les retrouver dans les cas d’utilisation. Ils sont à l’origine des requirements tels que définis plus haut.

Il est important pour une exigence qu’elle ne soit pas ambiguë (contrairement au terme "en" dans la consigne exprimée par la maman dans l’illustration ci-dessous : "Ramène moi 1 bouteille de lait. S’il y a des oeufs, ramène m’en 6.").

Joke
Figure 4. Spécification ambiguë (taken from here)

Dans le cadre de la matrice qui nous sert de plan, nous somme ici :

Requirements Structure Comportement Transverse

Organisation

Analyse

Conception

Implémentation

4.1. Fondements

On abordera :

  • L’organization des Requirements

  • Les Requirements properties

  • Les Requirements links

  • Les Requirements Diagrams

  • Les considérations sur la traçabilité

  • Annotations des Requirements

  • Les Use Case Diagrams

Tip

L’ingénierie des exigences est une discipline à part entière et nous n’abordons ici que les aspects en lien avec la modélisation. Voir le livre de référence pour plus de détails ([Sommerville1997]) ou le guide de l’AFIS ([REQ2012]).

Il n’existe pas de diagramme UML™ pour traiter des exigences en particulier. Nous allons donc nous servir dans cette partie d’un diagramme qui vient de SysML™.

4.2. SysML

4.2.1. Fiche d’identité

  • Date de naissance non officielle : 2001!

  • Première spécification adoptée à l’OMG™ : 19 septembre 2007

  • Version actuelle : 1.3 (12/06/2012)

  • Paternité : OMG™ / UML™ + INCOSE

  • Auteurs principaux :

    • Conrad Bock

    • Cris Kobryn

    • Sanford Friedenthal

  • Logo officiel : sysml

4.2.2. SysML, c’est…​

Un ensemble de 9 types de diagrammes
  • Diagrammes structuraux

    • Diagrammes de définition de blocs (bdd)

    • Diagrammes internes de blocs (ibd)

    • Diagrammes paramétriques (par)

    • Diagrammes de packages (pkg)

  • Diagrammes comportementaux

    • Diagrammes de séquence (sd)

    • Diagrammes d’activité (act)

    • Diagrammes de cas d’utilisation (uc)

    • Diagrammes d’états (stm)

  • Diagramme d’exigence (req)

Un profil UML™

C’est à dire une extension de cette notation, un ensemble de nouveaux concepts et éléments qui sont définis à partir des éléments de base d’UML™. Un exemple : le bloc SysML™ n’est qu’une redéfinition de la classe UML™.

Une notation

Une notation de plus en plus enseignée et connue et qui servira donc de plus en plus de référence à la modélisation des systèmes.

4.2.3. SysML, ce n’est pas…​

Une méthode

En effet, contrairement à ce que beaucoup pensent en l’abordant, SysML™ ne propose pas de démarche particulière de développement de système. C’est à la fois sa force (votre méthode existante pourra continuer à être utilisée) comme sa faiblesse car cette absence de guide méthodologique fait souvent défaut à son utilisation.

Un outil

Nous verrons en effet que SysML™ ne fait que ce qu’on veut bien en faire. Comme tout langage il est limité dans son pouvoir d’expression, mais surtout il reste une simple notation qu’il convient d’utiliser avec des outils et des démarches associées.

Un raton laveur

C’est juste pour voir ceux qui suivent…​

Note

On ne dit pas "le SysML" mais tout simplement "SysML".

4.3. L’organisation des Requirements

Il ne s’agit pas ici de revenir sur les exigences elles-même, mais plutôt de voir comment SysML™ permet de les exprimer, de les manipuler et surtout de les lier avec le reste du système.

4.3.1. Représentation de base

Un Requirement en SysML™ n’est qu’un bloc particulier.

Note
Définition : Requirements (OMG SysML v1.3, p. 139)

A requirement specifies a capability or condition that must (or should) be satisfied…​ A requirement is defined as a stereotype of UML Class…​

corde
Figure 5. Un Requirement en SysML (P)

4.3.2. Différents types d’organisation

L’ingénierie des exigences aboutit généralement à une liste organisée d’exigences, que ce soit en terme de fonctionnelles/non fonctionnelles, de prioritaires/secondaires, etc. Le principal support de SysML™ à cette organisation, outre la possibilité de les annoter (cf. section Stéréotyper les exigences), consiste à utiliser les packages.

Plusieurs types d’organisations sont possibles :

  • Par niveau d’abstraction

    • Besoins généraux (en lien avec les use cases par exemple)

    • Besoins techniques (en lien avec les éléments de conception)

  • Par point de vue

    • Besoins principaux (en lien avec les use cases)

    • Besoins spécifiques :

      • Fonctionnels

      • Marketing

      • Environnementaux

      • Business

      • …​

  • etc.

4.3.3. Tableaux de Requirements

Les requirements sont habituellement stockés dans des tableaux (feuilles excel le plus souvent!). Il est donc recommandé par le norme et possible dans de nombreux outils de représenter les exigences sous forme tabulaire.

Note
Définition : Requirements Table (OMG SysML v1.3, p. 145)

The tabular format is used to represent the requirements, their properties and relationships…​

req table
Figure 6. Exemples tableau d’exigences (OMG SysML v1.3, p. 145)

La plupart des outils modernes permettent le passage entre outils classiques de gestion des exigences (comme DOORS™) et outils de modélisation SysML™ (comme Modelio, illustré ci-dessous).

req modelio
Figure 7. Import Modelio de tableau d’exigences (tiré de [Modelio2012])

4.4. Les Requirements properties

Il est possible d’indiquer un certain nombre de propriétés sur un requirement :

  • priority (high, low, …​)

  • source (stakeolder, law, technical, …​)

  • risk (high, low, …​)

  • status (proposed, aproved, …​)

  • verification method (analysis, tests, …​)

Note

Dans le cadre du module MPA nous ne retiendrons comme attribut d’un requirement que son identifiant et le texte le désignnat (les deux attributs obligatoire). La priorité sera donné par le client en terme de cycle (on traitera en premier les requirements prioritaires).

Ainsi en plantUML, une exigence ressemblera à ceci (cf. rendu ici):

class ObtenirHoraires <<requirement>> {
	Text = "Le logiciel doit fournir les horaires rapidement."
	Id = "14.2"
	}

Les principales relations entre requirement sont :

Containment

Pour décrire la décomposition d’une exigence en plusieurs sous-exigences (⊕–). Typiquement dès qu’une exigence est exprimée avec une conjonction "et" ("La voiture doit être rapide et économe.").

Refinement

Pour décrire un ajout de précision ([refine]), comme par exemple une précision.

Derivation

Pour indiquer une différence de niveau d’abstraction ([deriveReqt]), par exemple entre un système et un de ses sous-systèmes.

Tip

Lorsqu’une exigence possède plusieurs cas [refine] qui pointent vers lui, on considère que ces différents cas sont des options possibles de raffinement (cf. [conventions]).

req exp1
Figure 8. Exemples de relations entre exigences (M, UK)
Tip

Il existe ensuite les relations entre les besoins et les autres éléments de modélisation (les block ou les class principalement) comme [satisfy] ou [verify], mais nous les aborderons dans la partie transverse.

topcased req connections
Figure 9. Relations liées aux requirements dans TOPCASED (T)

4.6. Les Requirements Diagrams

Voici un exemple de req un peu plus étoffé, tiré de la norme (voir aussi Exemples de rationale et problem (tiré de SysML, UK)) :

hsuv reqs1
Figure 10. Exemples de composition d’exigences (tiré de SysML, UK)

4.7. Stéréotyper les Requirements

Tout comme pour n’importe quel bloc, il est possible de stéréotyper les requirements. Ceci permet de se définir ses propres priorités et classifications. Quelques exemples de stéréotypes utiles :

4.8. Annotations des Requirements

Il est possible d’annoter les éléments de modélisation en précisant les raisons (rationale) ou les éventuels problèmes anticipés (problem).

hsuv reqs2
Figure 11. Exemples de rationale et problem (tiré de SysML, UK)

4.9. Les considérations sur la traçabilité

Une fois que les requirements ont été définis et organisés, il est utile de les lier au moins aux use cases (en utilisant [refine] par exemple) et aux éléments structurels (en utilisant [satisfy] par exemple), mais ceci sera abordé dans la partie transverse.

Note

En général chaque requirement devrait être relié à au moins un use case (et vice-versa!).

4.10. Les Use Case Diagrams

Bien que nous traitions les cas d’utilisation dans la partie comportement, nous les abordons ici du fait de leur proximité avec les requirements.

req uc relation
Figure 12. Exemple de lien entre use case et requirements (T, UK)

Ce diagramme est celui que vous avez appris l’an dernier en UML™.

UCGestionNotes
Figure 13. Exemple de diagramme des cas d’utilisation (B)
uc
Figure 14. Autre exemple de diagrammes des cas d’utilisation (B)
Tip

Un acteur représente un rôle joué par un utilisateur humain. Il faut donc plutôt raisonner sur les rôles que sur les personnes elles-mêmes pour identifier les acteurs.

4.11. Exigences et tests

4.11.1. Principes

Pour ce qui ce concerne ce module nous allons nous contenter de maintenir des matrices croisant les exigences d’un côté et les tests de l’autre.

Par exemple :

matrice
Figure 15. Exemple de matrice de traçabilité

Dans la réalité, les entreprises industrialisent le processus de vérification des exigences en utilisant des outils adaptés. Illustration tirée de [TestsIndustriels2009] :

testindus
Figure 16. Le cycle de la qualification fonctionnelle en lien avec les besoins métiers

4.12. Exemple complet

En prenant un exemple tiré d’un exercice que vous avez traité l’an dernier voici un exemple cohérent :

4.12.1. Le texte du cahier des charges

Le texte complet de l’exemple ne précise pas le cahier des charges de l’Autoradio (AR), considérant que tout le monde sait ce que c’est!

Rédigeons tout de même quelques extraits (numérotés) de texte possible :

  1. L’AR est un dispositif qui permet d’écouter la radio de manière confortable et interactive.

  2. L’AR doit être capable de mémoriser un certain nombre de station différentes.

  3. L’Utilisateur de l’AR doit pouvoir choisir sa station parmis un choix donné.

  4. L’Utilisateur de l’AR doit pouvoir régler le niveau sonore.

  5. L’Utilisateur de l’AR doit pouvoir chercher une station en "balayant" les ondes FM.

  6. …​

4.12.2. Expression des exigences

Nous pouvons, en analysant ce cahier des charges, déduire un certain nombre d’exigences. Nous les écrivons ici sous forme tabulaire, et en utilisant le langage Gherkin.

Note

Concernant Gherkin, pour ceux qui veulent aller plus loin, il est possible d’automatiser la génération des tests à partir de ce genre de langage. C’est ce que fait Cucumber pour Ruby.

Version tabulaire :

tabulaire
Figure 17. Exemple de liste d’exigences

Exemple de version textuelle formattée (fichier source ici):

#encoding: utf-8
Feature: Scénario simple d'utilisation de l'AutoRadio (AR)
  In order to vérifier que le son marche
  As an utilisateur lambda
  I should be able to exécuter ces scénarios et constater les effets

  Scenario: Augmenter le son
    Given un AR avec le son à 0
    When Je presse le bouton "Volume +"
    Then Le son passe à 1
    And Je commence à entendre la radio

4.12.3. Plan de test

Créer un plan de test consiste à prévoir l’ensemble des tests à l’avance de manière à prévoir la couverture de ces tests.

plantest
Figure 18. Exemple de plan de test simplifié

4.12.4. Analyse et la conception

Dans un cycle classique ("en V" par exemple), les modèles sont réalisés avant l’implémentation (codage).

AutoRadio UC
AutoRadio DC
AutoRadio DS Suivante

Dans un cycle Agile, chaque cycle possèdera ses modèles, eux aussi versionnés, qui eux aussi évolueront en même temps que le code.

4.12.5. Lien et traçabilité

Plus encore que dans les méthodes classiques, il conviendra de vérifier que code et modèles sont bien cohérents. On pourra donc :

Exemple de code Java commenté pour la génération automatique de diagrammes plantUML
package demo;

class Controller {}
class EmbeddedAgent {}
class PowerManager {}

/**
 * @extends Controller
 * @extends EmbeddedAgent
 * @navassoc - - 1..* PowerManager
 * @note this is a note
 */
class SetTopController implements URLStreamHandler {
  public String name;

  int authorizationLevel;
  void startUp() {}
  void shutDown() {}
  void connect() {}
}

/** @depend - friend - SetTopController */
class ChannelIterator {}

interface URLStreamHandler {
  void OpenConnection();
  void parseURL();
  void setURL();
  void toExternalForm();
}
doclet
Figure 19. Exemple de diagramme généré

4.13. En résumé

Les exigences sont très importantes en ingénierie logiciel, du fait de la multiplication des sous-systèmes et donc des intermédiaires (fournisseurs, sous-traitants, etc.) avec qui les aspects contractuels seront souvent basés sur ces exigences. Il n’est donc pas étonnant qu’un diagramme et des mécanismes dédiés aient été prévus en SysML™.

Table 2. Déclinaison des Exigences
Requirements Structure Comportement Transverse

Organisation

⊕–, \<<deriveReqt>>

Analyse

[satisfy], [refine]

[satisfy] entre reqs et UC

[refine]

Conception

\<<allocate>>

Implémentation

\<<satisfy>>, \<<verify>>

En terme de démarche, il est classique d’avoir de nombreux aller-retour entre la modélisation des exigences et la modélisation du système lui-même (cf. Exemple de démarche (SYSMOD Zigzag pattern)).

zigzag
Figure 20. Exemple de démarche (SYSMOD Zigzag pattern)

4.14. Concernant le projet

4.15. Questions de révision

Note
  1. Quelles sont les différences entre besoins et exigences ?

  2. Quelles sont les différences entre un backlog de produit et une exigences?

  3. En quoi les cas d’utilisation sont-ils complémentaires des exigences?

5. Documentations et modèles générés

5.1. Liens et traçabilités

Plus encore que dans les méthodes classiques, il conviendra de vérifier que code et modèles sont bien cohérents. On pourra donc :

5.2. Exemple concernant les exigences

On part des exigences (en Scrum, le Product Backlog) :

Backlogs
Figure 21. Exemple de "Product Backlog"

On les liste dans redmine :

La liste précise
Figure 22. La liste précise (redmine)

On les exporte dans un format manipulable (exemple .csv) :

Export CSV
Figure 23. Export des scénarios du "Product Backlog"

On les passes dans une moulinette maison pour obtenir du plantUML :

Exemple de conversion en PlantUML
@startuml

class Req_2205 <<Requirements>> {
Id = 2205
Text = "En tant qu'administrateur, je veux pouvoir afficher la liste des intervenants du fichier intervenants2014_2015.csv dans l'IHM"
}

class Req_2213 <<Requirements>> {
Id = 2213
Text = "En tant qu'administrateur, je veux pouvoir afficher la liste des sujets puis ajouter un nouveau sujet et sauvegarder la liste des projets dans un fichier .csv de mon choix"
}

class Req_2220 <<Requirements>> {
Id = 2220
Text = "En tant qu'administrateur, je veux pouvoir afficher la liste des étudiants indiquant le groupe, le sujet, le projet et l'ensemble des intervenants du projet dans l'IHM"
}

...
@enduml

Le fichier complet est disponible ici. Ce qui donne le rendu ci-dessous :

Diagramme des exigences
Figure 24. Diagramme des exigences (SysML) résultant
Note

Les exemples ne sont pas des corrections du projet en cours, mais sont donnés ici uniquement à titre d’illustration.

On réalise qu’il serait nécessaire de disposer d’une API digne de ce nom pour aller directement chercher les exigences dans redmine.

5.3. Générer un diagramme de classe à partir de Java commenté

Exemple de code Java commenté pour la génération automatique de diagrammes plantUML
package demo;

class Controller {}
class EmbeddedAgent {}
class PowerManager {}

/**
 * @extends Controller
 * @extends EmbeddedAgent
 * @navassoc - - 1..* PowerManager
 * @note this is a note
 */
class SetTopController implements URLStreamHandler {
  public String name;

  int authorizationLevel;
  void startUp() {}
  void shutDown() {}
  void connect() {}
}

/** @depend - friend - SetTopController */
class ChannelIterator {}

interface URLStreamHandler {
  void OpenConnection();
  void parseURL();
  void setURL();
  void toExternalForm();
}
doclet
Figure 25. Exemple de diagramme généré

5.4. Générer de l’asciidoc par javadoc

Pour aller un cran plus loin, vous pouvez même envisager de d’intégrer de l’AsciiDoc au moment de générer la documentation avec Javadoc!

asciidoclet diagram example
Figure 26. Exemple de diagramme généré
Tip

Pour plus d’info : Asciidoclet

On peut même utiliser la puissance des variables. Par exemple les commentaires Java suivants seront mis à jour en ajoutant les options suivantes au doclet :

-a product-name=OPTI -a version=1.0
/**
 * {product-name} will change your life!
 * @version {version}
 */
Tip

Cette astuce est aussi valable en AsciiDoc!

5.5. Tester la génération de doc

À partir du moment où la documentation est générée, on peut tester le programme qui la génère, comme n’importe quel programme.

Dans les exemples qui suivent on peut :

  • tester l’existence des fichiers qui sont inclus (e.g., include::foo.txt[])

  • tester la conformité avec les règles définies dans le sujet

  • tester la conformité aux bonnes pratiques

5.5.1. Les fichiers inclus existent-ils bien?

En utilisant un simple script Ruby (facilement intégrable en CI avec Travis par exemple) voici ce qu’on obtient :

checkImages note
Figure 27. Test : verification que les images existent bien

Voici le détail du script :

# CheckImage.rb
# 2014 -- JMB (initial code from JM Inglebert)
#----------------------------------------------------
re = Regexp.new("\.html$") # asciidoc result file (easier!)

dir = Dir.new('.')
dir.each  {|fn|
    if ( fn =~ re ) then
        print "asciidoc source : " + fn + "\n"
        paths = []
        # find all image: or image:: asciidoc macros
        File.open(fn) { |f|
          p 'opening ' << fn
            content = f.read
            paths = content.scan(/<img src="([^"]*)"/)
        }
        imagesDir='/Users/bruel/dev/Papyrus4Education/images'
        # test that path is a file
        paths.flatten.each {|path|
            print (File.file?(path) ? " OK " : " NOK ") + path + "\n"
        }
    end
}

5.5.2. Règles sur le contenu

On peut vérifier plusieurs aspects d’un document :

  • Que le contenu est conforme aux attentes

  • Que les bonnes pratiques ont été appliquées

5.5.3. Contenu conforme aux attentes

Le cahier des charges (http://algec.iut-blagnac.fr/~jmi/MPA/sprint_0.html) mentionne :

La documentation utilisateur devra fournir les informations suivantes :

- liste des membres de l'équipe et numéro de groupe
- Université Toulouse 2
- IUT de Blagnac
...

Voilà un exemple de script de test pour ces règles.

# == Synopsis
#   Petit programme de vérification de doc pour le projet MPA
#
# == Usage
#     ruby checkDoc.rb file membre groupe sprint
# => file : nom du fichier doc
# => membre : le nom d'un membre du groupe au hasard
# => groupe : le numéro du groupe
# => sprint : le numéro du sprint
#

unless ARGV.length == 4
  puts "Usage: ruby checkDoc.rb file membre groupe sprint\n"
  exit
end


#La documentation utilisateur devra fournir les informations suivantes :

file = ARGV[0]
membre = Regexp.new(ARGV[1])
groupe = Regexp.new(ARGV[2])
sprint = Regexp.new(ARGV[3])


f = File.open(file)
content = f.read

# liste des membres de l'équipe

res = content.scan(membre)
print "Membre : " + (res != [] ? " OK " : " NOK ") + "\n"

# numéro du groupe

res = content.scan(groupe)
print "Groupe : " + (res != [] ? " OK " : " NOK ") + "\n"

# Université Toulouse 2

res = content.scan(Regexp.new("Université Toulouse 2"))
print "UT2 : " + (res != [] ? " OK " : " NOK ") + "\n"

# IUT de Blagnac

res = content.scan(Regexp.new("IUT de Blagnac"))
print "IUT : " + (res != [] ? " OK " : " NOK ") + "\n"

# DUT INFO S3/Module MPA

res = content.scan(Regexp.new("DUT INFO S3/Module MPA"))
print "MPA : " + (res != [] ? " OK " : " NOK ") + "\n"

# le nom du projet : OPTI

res = content.scan(Regexp.new("OPTI"))
print "OPTI : " + (res != [] ? " OK " : " NOK ") + "\n"

# le SPRINT concerné

res = content.scan(Regexp.new(sprint))
print "SPRINT : " + (res != [] ? " OK " : " NOK ") + "\n"

# La documentation utilisateur :

# contiendra une section présentant le backlog de produit du projet OPTI connu en début de SPRINT

# décrira toutes les fonctionnalités disponibles à la fin du SPRINT

Ce qui donne :

checkDoc
Figure 28. Test de contenu de doc

5.5.4. Règles sur les bonnes pratiques

Papyrus doc
Figure 29. Un exemple de la vie réelle : la documentation Papyrus

Voici un exemple qui vérifie que la documentation est conforme aux règles Eclipse Doc Style Guide.

Par exemple la Eclipse Doc Style Guide préconise :

Use sentence capitalization for all titles.

Voilà le script de test pour cette règle.

#require 'minitest/spec'
require 'minitest/autorun'

#---------------------------------------------------
# Checking Titles
#---------------------------------------------------
    MAIN='main.wiki'
    File.open(MAIN) { |f|
          content = f.read
          titles = content.scan(/=+ (.*) =+/)
          # test that titles have Capital first letter
          titles.flatten.each {|title|
            describe File do
              it "Wiki should use sentence capitalization for all titles" do
                assert_match(/[A-Z].+$/, title)
              end
            end
          }
        }

Et le résultat :

checkTitles note
Figure 30. Vérification que les titres ont bien une majuscule
Note

Bien sûr tout n’est pas testable. Exemple de règle difficile à instrumenter : "Wherever possible, make statements positive."

5.6. "Asciidoc ne marche pas sur ma machine!"

Tip

Alors utiliser l’intégration continue ([CI]) et la virtualisation!

Nous allons détailler l’exemple d’un cas concret :

framework
Figure 31. Le cas de la (future) documentation Papyrus

5.6.1. [0] Le client fournit les templates, CSS stylesheets, …​

Hors de propos, mais en tant que programmeur, c’est très pratique.

StylesheetsDefinition
Figure 32. Un exemple de CSS Papyrus
Note

Vous n’auriez pas en avoir bénéficié en MPA?

5.6.2. [1] Les contributeurs fournissent les inputs, en s’occupant du contenu

De la même façon que vous avez conçus vos fichiers sources AsciiDoc.

5.6.3. [2] Tout est versionné et contrôlé

Dans notre exemple, nous utilisons GitHub.

5.6.4. [3] Travis est utilisé pour lancer les tests et générer les outputs

Cf. détails sur la configuration ci-après.

5.6.5. [4] Le résultat est disponible sur le web sur de multiples formats

Les formats courants sont supportés :

  • PDF

  • ebook

  • HTML

  • Slides (Deck.js, Reveal.js, slidy2, …​)

  • Docx

  • …​

5.7. Configuration

Le but de ces notes est d’expliquer le fonctionnement de la génération de document HTML par intégration continue en utilisant Travis en complément des dépôts GitHub.

La démarche globale (cf. Un processus d’intégration continue):

  1. Se connecter à Travis avec ses identifiants GitHub.

  2. Configurer les dépôts à "intégrer" de manière continue

  3. Ajouter un fichier .travis.yml à la racine du dépôt (penser à l’ajouter : git add)

  4. Lors du git push (après un git commit bien sûr), Travis va générer une machine virtuelle qui va exécuter le script et indiquer un succès (passing) si tout c’est bien passé.

travis
Figure 33. Un processus d’intégration continue

5.8. Connection entre Github et Travis

Pour ne pas avoir à préciser les mots de passe en clair dans vos scripts, il est possible d’indiquer les éléments de connexions de manière crypté. Ainsi il faut :

  1. Associer un token à votre dépôt sous GitHub (cf. explications ici).

  2. Installer Travis

    gem install travis
  3. Crypter (et ajouter au fichier .travis.yml en même temps) votre token

    travis encrypt MY_SECRET_ENV=super_secret --add env.matrix
Note

Il est possible de valider la syntaxe du fichier .travis.yml en installant un utilitaire :

gem install travis-lint
travis-lint

5.9. Exemple de fichiers

5.9.1. Un fichier Travis

".travis.yml"
#language: python
#python:
#- '2.7'
install:
- gem install asciidoctor
- gem install link-checker

script:
#- asciidoctor --version
#- ls -alF
#- whereis bash
- asciidoctor -a icons -a linkcss! -a numbered faq.txt -o output/faq.html
#- ls -al output
#- bash update-doc.sh
- rake check_links

# Following generated by
#
# travis login --pro
# travis encrypt -r jmbruel/PapyrusFAQ GH_TOKEN=<token generated on gitHub> --add env.global
env:
  global:
    secure: cEaBJq02ObnKSWQHP0c.....WMQX8Py4icaC8Cn9l62AqE4=

# if everything OK, then deploy on the web
after_success:
- bash update-doc.sh

5.9.2. Un fichier de script lancé par Travis

update-doc.sh
#!/bin/bash
echo -e "Starting to update doc\n"

#copy data we're interested in to other place
cp -R output $HOME/output

#go to home and setup git
cd $HOME
git config --global user.email "jbruel#travis@gmail.com"
git config --global user.name "Jean-Michel Bruel"
git config --global push.default simple

#using token clone io pages branch
git clone --quiet https://${GH_TOKEN}@github.com/jmbruel/jmbruel.github.io.git  doc > /dev/null

#go into directory and copy data we're interested in to that directory
cd doc
cp $HOME/output/faq.html ./index.html
ls -al index.html

#add, commit and push files without provoking Continuous Integration
git add -f index.html
git commit -m "Travis build $TRAVIS_BUILD_NUMBER pushed to io pages -- [skip ci]"
git push -fq origin master > /dev/null

echo -e "Done magic with output\n"
Tip

Notez le [skip ci], qui permet d’éviter la récursivité du processus (modif du push donc relance du script!).

5.9.3. Branches et SVN

Il n’est pas normal de ne pas pouvoir présenter une release qui fonctionne.

Tip

Voir l’équivalent pour git ici.

svn branch create
Figure 34. La boîte de dialogue branch/tag (source ici)

5.9.4. Questions de révision

Note
  1. Pour ceux qui ont le support avec eux (ordi, tablette, portable) : trouvez un exemple de violation de la bonne pratique [DRY] dans ce support de cours (indice : mes codes Ruby sont souvent écrits à l’arrache)

  2. Pourquoi les concepteurs de Papyrus insistent-ils sur la qualité de leur documentation?

Glossaire

Acronymes UML/SysML

act

Raccourcis pour Diagramme d'ACTivité dans une cartouche SysML™

bdd

Raccourcis pour Block Definition Diagram dans une cartouche SysML™

dc

Diagramme de Classe UML™

dss

Diagramme de Séquence Système (un sd où seul le système dans sa globalité est représenté [1])

ibd

Raccourcis pour Internal Block Diagram dans une cartouche SysML™

par

Raccourcis pour Parametric Diagram dans une cartouche SysML™

pkg

Raccourcis pour PaKaGe Diagram dans une cartouche SysML™

req

Raccourcis pour REQuirements Diagram dans une cartouche SysML™

sd

Raccourcis pour SEQquence Diagram dans une cartouche SysML™

stm

Raccourcis pour STate Machine dans une cartouche SysML™

uc

Raccourcis pour Use Case Diagram dans une cartouche SysML™

Définitions générales

Note
Ressources

Les définitions ci-dessous sont regroupées à titre indicatif. Je vous invite à consulter les sources suivantes :

CI

Continuous Integration : (Intégration Continue) est un ensemble de pratiques utilisées en génie logiciel consistant à vérifier à chaque modification de code source que le résultat des modifications ne produit pas de régression dans l’application développée (source link: ici).

DRY

Don’t Repeat Yourself : Un bon principe qui veut qu’on évite de répéter des tâches manuelles (comme les tests) en utilisant plutôt des scripts et des programmes.

OMG

Object Management Group : L’organisme international chargé des principales normes liés à l’objet (CORBA, UML, etc.).

TDD

Test Driven Development : Développements dirigés par les tests. On écrit les tests avant d’écrire le code. On travaille son code tant que les tests ne passent pas.

TRL

Technology Readiness Level : Système de mesure employé par des agences gouvernementales américaines et par de nombreuses compagnies (et agences) mondiales afin d’évaluer le niveau de maturité d’une technologie (cf. Wikipedia).

STI2D

Sciences et Technologies de l'Industrie et du Développement Durable : série du baccarauléat qui met l’accent sur les technologies transversales et qui a introduit en 2011 l’enseignement de SysML™.

SysML

System Modeling Language ™ : Le langage de modélisation de systèmes maintenu par l’OMG™.

UML

Unified Modeling Language ™ : Le langage de modélisation généraliste maintenu par l’OMG™.

Liens utiles

Références

Voici quelques références utiles.

  • [ENS2013] L. Gendre et J.-M. Virely, SysML. Tutoriel du 13/06/2013. ENS Cachan.

  • [FIO2012] Fiorèse S., Meinadier J., Découvrir et comprendre l’ingénierie système, AFIS 2012.

  • [FMS] A. Moore, R. Steiner, S. Friedenthal, A Practical Guide to SysML, The MK/OMG Press, MK/OMG Press, 2011 (2nd edition).

  • [Fejoz2013] Loïc Fejoz. SysML4STI2D, présentation de SysML en STI2D, 2004. Disponible ici.

  • [Fowler2004] Martin Fowler. UML 2.0 INFORMATIQUE PROFESSIONNELLE, 2004.

  • [HAS2012] Haskins C., SE Handbook Working Group, INCOSE Systems Engineering Handbook: Version 3.2.2, International Council on Systems Engineering, 2012.

  • [Harmony] Bruce Powel Douglass. Real-Time Agility: The Harmony/ESW Method for Real-Time and Embedded Systems Development. Addison-Wesley Professional, 2009. ISBN-10: 0-321-54549-4

  • [KAP2007] Kapurch S., NASA Systems Engineering Handbook, 2007 (pdf).

  • [MeDICIS] ENSI Bourges/PRiSM.

  • [Modelio2012] Systems Engineering using Modelio, INCOSE 2012 Tool Vendor Challenge Case Study. Disponible ici.

  • [OMG2009] The Current State of Model Based Systems Engineering: Results from the OMG SysML Request for Information. Mary Bone and Robert Cloutier, 2009. Disponible ici.

  • [REQ2012] Guide Bonnes Pratiques en Ingénierie des Exigences, AFIS 2012.

  • [Roques2010] Pascal Roques. SysML par l’exemple - Un langage de modélisation pour systèmes complexes. Eyrolles. À obtenir ici.

  • [SeeBook2012] Embedded Systems Analysis and Modeling with SysML, UML and AADL, F. Kordon, J. Hugues, A. Canals, A. Dohet, Wiley, 2013.

  • [Sommerville1997] Ian Sommerville, Pete Sawyer. Requirements Engineering: A Good Practice Guide. Wiley, 1997.

  • [Styles] Scott W. Ambler. The Elements of UML 2.0 Style. Cambridge University Press, 2005. ISBN: 0-521-61678-6

  • [SysML] OMG. Systems modeling language version 1.3. Technical report, 2012. Available here.

  • [Walsh1999] Norman Walsh & Leonard Muellner. DocBook - The Definitive Guide. O’Reilly & Associates. 1999. ISBN 1-56592-580-7.

  • [TAOUP] Eric Steven Raymond. 'The Art of Unix Programming'. Addison-Wesley. ISBN 0-13-142901-9.

  • [TestsIndustriels2009] Guide méthodologique de l’industrialisation et référentiel de bonnes pratiques. Disponible ici.

A propos de ce document…​

Document généré par Jean-Michel Bruel via Asciidoctor (version 0.1.5) de 'Dan Allen', lui même basé sur AsciiDoc. Pour l’instant ce document est libre d’utilisation et géré par la 'Licence Creative Commons'. Licence Creative Commons licence Creative Commons Paternité - Partage à l'Identique 3.0 non transposé.


1. Il ne s’agit pas d’un acronyme SysML™ à proprement parler mais nous l’utilisons beaucoup.